beansieve 账本整理工具

beansieve 是一个用于整理 beancount 账本的小工具。这个工具主要实现以下两个功能：

1. 通过
   --type aggregate
   将账单中包含特定账户的条目放到一个新账本文件中。
2. 通过
   --type archive
   将特定时间范围内的 Transaction 条目保留到一个新账本文件中。

项目可以在 Github 上查看。 使用

进行安装，并通过 使用，具体用法参考下面的例子。

一些术语

• type
  ：操作类型，即
  aggregate
  按账户拆分账本或
  archive
  按时间范围归档账本；
• source
  ：源文件，即要操作的账本文件；
• dest
  ：目标文件，即新生成的账本文件的保存目录；
• rule
  ：使用
  aggregate
  时用于指定聚合规则；
• keep
  ：使用
  archive
  时用于指定保留时间范围。

Structure 输出文件的结构

运行该工具后会使用

重新组织账本文件，组织规则如下：

── account.beancount      # 账户相关指令，即 `open` 和 `close`
├── commodity.beancount   # commodity 指令
├── custom.beancount      # custom 指令（如 fava 中提供的 balance 指令）
├── document.beancount    # document 指令
├── event.beancount       # event 指令
├── history.beancount     # 如果使用 `archive`，则 `keep` 范围外的 Transaction 会被移动到此文件夹中
├── main.beancount        # 主账本文件，include 其他账本文件，如果使用 `archive` 则会包含 `keep` 范围内的 Transaction，如果使用 `aggregate` 则未匹配上的 Transaction 文件会被移动到此文件
├── note.beancount        # note 指令
├── price.beancount       # price 指令
├── <key>.beancount       # 使用 `aggregate` 时按 `rule` 拆分出来的账本
└── query.beancount       # query 指令
📋

aggregate 的用法

使用

将账单中包含特定账户的条目放到一个新账本文件中。 通过使用 设置账户匹配规则，支持设置多种规则，单条规则的格式为 ，其中 为文件名称， 为一个用于匹配账户名称的正则表达式。如果有多条规则则使用 分割匹配规则。

例如下面的脚本会将 ：

1. posting
   中账户名称匹配
   Income:US:ETrade:.*
   的 Transaction 移动到
   Etrade.beancount
   文件；
2. posting
   中账户名称匹配
   Income:US:Babble:Salary
   的 Transaction 移动到
   Payroll.beancount
   文件；
3. 其他的
   Transaction
   移动到
   main.beancount
   文件；
4. 其他的
   Directive
   会按照
   Structure
   规则移动到特定的文件中。

# generate sample beancount files
bean-example > .artifacts/example.beancount
bean-report .artifacts/example.beancount balances > .artifacts/example-balances.txt

# aggregate
rm -rf .artifacts/example_aggregate
python -m beansieve \
  --type aggregate \
  --source ".artifacts/example.beancount" \
  --dest ".artifacts/example_aggregate" \
  --rule "Etrade|Income:US:ETrade:.*,Payroll|Income:US:Babble:Salary"
bean-report .artifacts/example_aggregate/main.beancount balances > .artifacts/example_aggregate-balances.txt
📋

archive 的用法

使用

能够保留将特定时间范围内的 条目移动到 文件中，时间范围外的 会被移动到 文件中。 其中 用于指定从当前时刻其回溯的时间范围，比如 表示自当前时刻起前 1 天的 Transaction 会被保留到 文件中， 则保留前 7 天的条目， 保留前 30 天的条目。 例如下面的脚本会将：

1. 从当前时刻起前 7 天的
   Transaction
   移动到
   main.beancount
   文件；
2. 其他
   Transaction
   移动到
   history.beancount
   文件；
3. 其他的
   Directive
   会按照
   Structure
   规则移动到特定的文件中。

# generate sample beancount files
bean-example > .artifacts/example.beancount
bean-report .artifacts/example.beancount balances > .artifacts/example-balances.txt

rm -rf .artifacts/example_archive
python -m beansieve \
  --type archive \
  --source ".artifacts/example.beancount" \
  --dest ".artifacts/example_archive" \
  --keep 7d
bean-report .artifacts/example_archive/main.beancount balances > .artifacts/example_archive-balances.txt
📋

注意

1. 这个工具不能保证输入(
   --source
   )文件结构的完整性，因此如果有使用
   include
   拆分账本文件的习惯，请先确保你认同
   Structure
   的拆分规则；
2. aggregate
   和
   archive
   这两个命令不能同时使用。对我而言只是当有拆分
   Transaction
   的时候才会使用
   aggregate
   拆分账本，更多时候是通过
   archive
   来确保最近一段时间的账本文件（
   main.beancount
   ）足够精简；
3. 使用前做好备份，以防止数据丢失，在使用前后使用
   bean-report
   生成
   balances
   报表进行对比，可以确保转换无误。